<HTML><HEAD><TITLE>hash_insert_suspension(+Table, +Susp, -Notifications)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">library(hash)</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>hash_insert_suspension(+Table, +Susp, -Notifications)</H1>
Attach a suspension to be woken on hash table modifications
<DL>
<DT><EM>Table</EM></DT>
<DD>Hash table
</DD>
<DT><EM>Susp</EM></DT>
<DD>A suspension
</DD>
<DT><EM>Notifications</EM></DT>
<DD>A receive port, see library(notify_ports)
</DD>
</DL>
<H2>Description</H2>

        Attach a suspension Susp to the hash table Table such that it gets
	woken whenever the table changes (i.e. when entries are added, changed
	or removed).
	<p>
	The suspended goal would typically be a demon (because it is going to
	be woken repeatedly, on every change). hash_insert_suspension/3 also
	supplies a Notifications argument, which should be used as one of the
	arguments of the suspended goal (see example). This is a "receive
	port" as defined by library(notify_ports), and is used to convey
	information about the changes that happened to the hash table.
	The notifications are of the following form:
	<dl>
	<dt>add(Key,Value)</dt>             <dd>if a table entry was added</dd>
	<dt>chg(Key,OldValue,NewValue)</dt> <dd>if a table entry was modified</dd>
	<dt>rem(Key,OldValue)</dt>          <dd>if a table entry was removed</dd>
	</dl>
	Note that the suspensions will be always be woken <B>after</B> the hash
	table has changed, so they will see the new state when they wake up.
    
<H3>Modes and Determinism</H3><UL>
<LI>hash_insert_suspension(+, +, -) is det
</UL>
<H2>Examples</H2>
<PRE>
    % Program:

	hash_create_verbose(H) :-
	    hash_create(H),
	    make_suspension(report(Notifications,Susp), 2, Susp),
	    hash_insert_suspension(H, Susp, Notifications).

	:- demon(report/2).
	report(Notifications, Susp) :-
	    notify_ports:receive_notifications(Notifications, List, Status),
	    writeln(changes:List),
	    ( Status = closed -&gt; kill_suspension(Susp) ; true ).


    % Sample execution

    ?- hash_create_verbose(H),
       hash_set(H,k1,v1), hash_set(H,k1,v2), hash_delete(H,k1),
       hash_terminate_suspensions(H).
    changes : [add(k1, v1)]
    changes : [chg(k1, v1, v2)]
    changes : [rem(k1, v2)]
    changes : []

    H = hash(4, 0, [])
    Yes (0.00s cpu)
    </PRE>
<H2>See Also</H2>
<A HREF="../../lib/hash/hash_terminate_suspensions-1.html">hash_terminate_suspensions / 1</A>, <A HREF="../../lib/notify_ports/receive_notifications-3.html">notify_ports : receive_notifications / 3</A>, <A HREF="../../lib/notify_ports/foreachnotification-6.html">notify_ports : foreachnotification / 6</A>, <A HREF="../../lib/notify_ports/index.html">library(notify_ports)</A>, <A HREF="../../kernel/compiler/demon-1.html">demon / 1</A>
</BODY></HTML>
